home *** CD-ROM | disk | FTP | other *** search
/ Mac Format 1996 April / MacFormat CD Edition MF36 (April 1996).iso / Shareware City / Developers / Tools Plus - GUI⁄Event libs / Tools Plus 2.6.1a Evaluat'n Kit / Tools Plus 2.6.1a / User Manual / 11-Pop-Up Menus (1 of 2) < prev    next >
INI File  |  1995-04-01  |  25KB  |  326 lines
  1. [Display using Monaco 9]
  2.  
  3.  
  4. 11 Pop-Up Menus
  5. ```````````````
  6.  
  7.   Pop-up menus are a mechanism that lets the operator make a selection from multiple choices.  Where this interface differs from a set of radio buttons, a set of check boxes, or a list box, is that a pop-up menu requires minimal space on a window by hiding most of its detail until it is required.  Pop-up menus are typically used for lists of items, such as fonts.  See the Macintosh User Interface Guidelines chapter of Inside Macintosh for details on the use of pop-up menus.  The implementation of pop-up menus shares many similarities with pull-down menus, so you will find that this chapter has a lot of function commonalty with the chapter on Menus.
  8.  
  9.   A pop-up menu is typically made up of two components: a title, and a pop-up box.  The pop-up box contains the selected item, and a “down arrow” which provides the user with a visual cue that the control is a pop-up menu.  When the user clicks and holds the title or the pop-up box, a list of choices is displayed in a pop-up menu, allowing the user to select one of the items.  By default, Tools Plus pop-up menus allow only a single item to be selected, but you can easily override this behavior.
  10.  
  11.   Tools Plus’s pop-up menus provide several options that are not available on ordinary Macintosh pop-up menus.  One of these options displays the selected item’s icon within the pop-up box.  You can also suppress the “down arrow” if you want.  Tools Plus’s pop-up menus also perform automatic adjustments to create the perfect looking pop-up menu without having to calculate font heights.
  12.  
  13.   Another feature that is not available in ordinary Macintosh pop-up menus is the “Fixed Title” option, which lets you create a pop-up menu with a fixed title inside the pop-up box (instead of displaying the selected item).  With this option, the menu “pops down” below the control.  This feature is useful in a dialog where space is restricted and several “do it now” options are required.
  14.  
  15.   In this document, the term pop-up menu refers to the entire control; that is, the pop-up box and its contents, the name that appears to the left, and the individual items which appear during selection.  The term menu item or item refers to individual items found within a pop-up menu.  The item number is determined by counting from the top of the list, the first item being 1, the second being 2, etc.
  16.  
  17.   A pop-up menu is created on the current window with the NewPopUp procedure.  Each pop-up menu is referenced by a unique pop-up menu number that can be from 1 to 255.  This number is specified when the pop-up menu is created, and refers to the specific pop-up menu until it is deleted.  Note that the pop-up menu number is related to its associated window.  This means that two different windows can each have a pop-up menu numbered “1” without interfering with each other.  Whenever the user makes a selection in the pop-up menu, PollSystem reports this to your application.
  18.  
  19.   The PopUpMenu procedure is used to add items to a specific pop-up menu, or to rename existing items in a pop-up menu.
  20.  
  21.   Pop-up menu items can also be inserted between others using the InsertPopUpItem procedure.  This lets your application maintain a dynamic pop-up menu that may be used, for example, for a list of available font sizes.
  22.  
  23.   An entire pop-up menu can be deleted by using the RemovePopUp procedure.  This procedure reclaims the memory used by the pop-up menu.  Individual items can also be deleted using this procedure.
  24.  
  25.   Pop-up menu items can be renamed by using the RenamePopUp procedure.  This should be done judicially, since changes to pop-up menu items may prove to be confusing to the user.
  26.  
  27.   An entire pop-up menu can be enabled or disabled with the EnablePopUp procedure, as can individual menu items.  When an entire pop-up menu is disabled, it is dimmed and it cannot be selected.  Furthermore, its items cannot be displayed.  When an item is disabled, it becomes dim and cannot be selected.
  28.  
  29.   Various other menu item-related features are supported, such as setting or removing “check marks” with the CheckPopUp procedure.  You can set or remove other marks with the PopUpMark procedure, and determine which mark is displayed by using GetPopUpMark.  You can set and retrieve an item’s icon number with PopUpIcon and GetPopUpIcon.  An item’s text is retrieved with GetPopUpString, and its style is set with PopUpStyle.
  30.  
  31.  
  32.  
  33.  
  34.  
  35. Command Key Equivalents & Hierarchical Pop-Up Menus
  36. ```````````````````````````````````````````````````
  37.   Tools Plus does not support keyboard equivalents (command keys) in pop-up menu items, nor does it support hierarchical menus within pop-up menus.  This is consistent with the User Interface Guidelines as described in Inside Macintosh.
  38.  
  39.  
  40.  
  41.  
  42.  
  43. Handling Pop-Up Menus
  44. `````````````````````
  45.   Once a pop-up menu is created, Tools Plus performs all the processing required to maintain it.  When a window in inactive, Tools Plus disables all pop-up menus on that window.  When the window is activated again, all the pop-up menus regain their correct status as specified by your application.  The PollSystem function is used to constantly inquire about any actions occurring in a pop-up menu.
  46.  
  47.   Several types of events may indicate that your application has to perform some action.  For example, you may want to enable or disable buttons based on whether a selection has been made in the pop-up menu.  Or you may ignore all pop-up menu action and use GetPopUpSelection to determine the selected item only after an OK button is clicked.  Though various interpretations can be implemented, please adhere to the Macintosh User Interface Guidelines as outlined in Inside Macintosh Volume I.  In any case, PollSystem tells your application if any activity has occurred in a list box, or if a selection has been double clicked.
  48.  
  49.   See the PollSystem function for complete details on the handling of pop-up menus.
  50.  
  51. ------------------------------------------------------------------------
  52.  
  53. NewPopUp
  54. ````````
  55. Create a new pop-up menu.
  56.  
  57.    pascal void NewPopUp (short MenuNumber,
  58.                  short left, short top, short right, short bottom,
  59.                  Str255 MenuTitle, short procID, Boolean EnabledFlag);
  60.  
  61.    procedure NewPopUp (MenuNumber, left, top, right, bottom: INTEGER;
  62.                  MenuTitle: STRING; procID: INTEGER;
  63.                  EnabledFlag: BOOLEAN);
  64.  
  65.   This procedure just creates the pop-up menu control and its title.  Pop-up menu items are created with PopUpMenu.
  66.  
  67.   MenuNumber specifies the pop-up menu number (from 1 to 255) that is created in the current window.  Once a pop-up menu is created, it is referenced by this pop-up menu number.  If a pop-up menu has been previously created in the current window using the same number, it is replaced with a new pop-up menu (without any items) as specified by the parameters in the NewPopUp procedure.  If the current window doesn’t belong to your application, or if no windows are open, NewPopUp does nothing.
  68.  
  69.   Left, top, right, and bottom define a rectangle in the current window’s local co-ordinates that determine the pop-up menu’s size and location in the window.  These parameters can be seen as two corners; the upper left-hand corner (left,top) and the bottom right-hand corner (right,bottom) of the pop-up box.  The pop-up box’s 1-pixel border and its drop shadow are drawn outside these co-ordinates.  Also, the pop-up menu’s title is drawn to the left of the specified rectangle.  To make a pop-up menu operate at its best, its height (difference between top and bottom) must be equivalent to the font’s height (font height can be determined by calling the GetFontInfo procedure and adding Ascent + Descent + Leading).  If you make bottom equal to top, the bottom is adjusted automatically to the exact font height.  If your menu is comprised entirely of icons (no text in the items), set the height of the rectangle to equal the height of the icon, and add 2.
  70.  
  71.   MenuTitle is the pop-up menu’s name that appears to the left of the pop-up box, or inside the pop-up box when the “Fixed Title” option is used.  You may specify a null string (‘’) if you do not want to have an external title displayed.
  72.  
  73.   ProcID specifies the pop-up menu’s appearance and behavior characteristics.  The value for this 2-byte integer can be specified either by adding a set of constants to obtain the desired result, or using a specially defined variant record.  See the section below for details.
  74.  
  75.   EnabledFlag indicates if the newly created pop-up menu is enabled or not.  When a pop-up menu is disabled, it becomes dim and cannot be selected by the user, nor can its items be viewed.  All pop-up menus automatically become disabled when the window containing them is inactive.  When the window is activated, the pop-up menus assume their state as set by the NewPopUp procedure and subsequent calls to the EnablePopUp procedure.  The two constants that can be used for this flag are enabled and disabled.
  76.  
  77.  
  78.  
  79. Pop-Up Menu’s Appearance and Behavior
  80. `````````````````````````````````````
  81.   ProcID specifies the pop-up menu’s appearance and behavior characteristics.  The value for this 2-byte integer can be specified either by adding a set of constants to obtain the desired result, or using a specially defined variant record, as illustrated below.
  82.  
  83.   popupNeverDimOutline     Never dim the pop-up box.  By default, the
  84.                            pop-up box is dimmed when the pop-up menu is
  85.                             disabled or when its parent window is
  86.                             inactive.
  87.  
  88.   popupNeverDimSelection   Never dim the selected item's text (and the
  89.                            optional icon and “down arrow”) displayed in
  90.                            the pop-up box.  By default, the selected
  91.                            item is dimmed when the pop-up menu is
  92.                            disabled or when its parent window is
  93.                            inactive.  This option is useful when using
  94.                            small fonts on a black and white monitor,
  95.                            since those fonts tend to look illegible when
  96.                            dithered.
  97.  
  98.   popupNeverDimTitle       Never dim the external title.  By default,
  99.                            the external title is dimmed when the pop-up
  100.                            menu is disabled or when its parent window is
  101.                            inactive.  This option is useful when using
  102.                            small fonts on a black and white monitor,
  103.                            since those fonts tend to look illegible when
  104.                            dithered.
  105.  
  106.   popupNoArrow             Suppress the "down arrow."  By default, the
  107.                            “down arrow” is displayed in the pop-up box.
  108.  
  109.   popupMultiSelect         Allow multiple items to be selected.  By
  110.                            default, pop-up menus allow only a single
  111.                            item to be selected at a time (selecting
  112.                            another item deselects the original one).
  113.  
  114.   popupUseWFont            Use the window's font for the menu.  By
  115.                            default, pop-up menus use the System Font
  116.                            (Chicago 12pt.)  You may want to use a
  117.                            smaller font, such as Geneva 9, in windows
  118.                            where space is scarce.
  119.                              When using this option, the window’s
  120.                            current font, size and style settings (as set
  121.                            by the TextFont, TextSize, and TextFace
  122.                            procedures) are remembered by the pop-up menu
  123.                            as it is created.  The window’s font settings
  124.                            (font, size, text-transfer mode, and style)
  125.                            can then be changed without affecting the
  126.                            pop-up menu.
  127.  
  128.   popupIconTitle           Draw the selected item’s icon in the pop-up
  129.                            box.  By default, the selected item’s icon is
  130.                            not drawn in the pop-up box regardless if
  131.                            icons are used in the pop-up menu or not.
  132.  
  133.   popupFixedTitle          Display a fixed title in the pop-up box.
  134.                            This option lets you override the default
  135.                            “pop-up menu” behavior to create a control
  136.                            with a constant (fixed) title, and that “pops
  137.                            down” a list of items.
  138.  
  139.   popupDefaultType         This constant, if used alone, produces a
  140.                            standard pop-up menu using Chicago 12 that
  141.                            allows one item to be selected at a time.
  142.  
  143.  
  144.  
  145.   So, if you want to create a pop-up menu that uses the window’s current font settings instead of Chicago 12, and you wanted the selected item’s icon to be displayed in the pop-up box, you should use the combined constants popupUseWFont + popupIconTitle.  Alternatively, a C structure and a Pascal variant record are available to help you define the ProcID in a more intuitive way, as shown below:
  146.  
  147.  
  148.  
  149. union TPPopUpMenuSpec {        /*Pop-Up Menu's appearance and behavior*/
  150.                                /*  specifications in 2 formats…       */
  151.   struct{                      /* • Parsed into components:           */
  152.     unsigned short bit15 :1;         /*     (reserved bit)            */
  153.     unsigned short bit14 :1;         /*     (reserved bit)            */
  154.     unsigned short bit13 :1;         /*     (reserved bit)            */
  155.     unsigned short bit12 :1;         /*     (reserved bit)            */
  156.     unsigned short bit11 :1;         /*     (reserved bit)            */
  157.     unsigned short bit10 :1;         /*     (reserved bit)            */
  158.     unsigned short bit9 :1;          /*     (reserved bit)            */
  159.     unsigned short NeverDimOutline :1;     /* Never dim outline       */
  160.     unsigned short NeverDimSelectedItem: 1;/* Never dim selected item */
  161.     unsigned short NeverDimTitle: 1;       /* Never dim the title     */
  162.     unsigned short NoArrow: 1;             /* Hide "down arrow"       */
  163.     unsigned short MultipleSelections: 1;  /* Allow multi-selections  */
  164.     unsigned short UseWindowFont: 1;       /*    Using window's font  */
  165.     unsigned short IconInTitle: 1;   /*    Draw selected item’s icon  */
  166.     unsigned short FixedTitle: 1;    /*    Display fixed title        */
  167.     unsigned short bit0 :1;          /*     (reserved bit)            */
  168.   } Bits;                            /*                               */
  169.   short Num;                         /* • Short equivalent            */
  170. };                                   /*                               */
  171. typedef union TPPopUpMenuSpec TPPopUpMenuSpec;
  172.  
  173.  
  174. TPPopUpMenuSpec = packed record  {Pop-Up Menu's appearance and behavior}
  175.                                  {  specifications in 2 formats…       }
  176.   case integer of                {                                     }
  177.     0: (                             { • Parsed into components:       }
  178.       bit15, bit14, bit13: boolean;  {      (reserved bits)            }
  179.       bit12, bit11, bit10: boolean;  {      (reserved bits)            }
  180.       bit9: boolean;                 {      (reserved bits)            }
  181.       NeverDimOutline: boolean;      {     Never dim outline           }
  182.       NeverDimSelectedItem: boolean; {     Never dim selected item     }
  183.       NeverDimTitle: boolean;        {     Never dim the title         }
  184.       NoArrow: boolean;              {     Hide "down arrow"           }
  185.       MultipleSelections: boolean;   {     Allow multiple selections   }
  186.       UseWindowFont: boolean;        {     Display using window's font }
  187.       IconInTitle: boolean;          {     Draw selected item’s icon   }
  188.       FixedTitle: boolean;           {     Display fixed title         }
  189.       bit0: boolean;                 {      (reserved bit)             }
  190.     );                               {                                 }
  191.     1: (                             { • Integer equivalent:           }
  192.       Num: integer;                  {     Specification integer       }
  193.     );                               {                                 }
  194.   end;
  195.  
  196.  
  197.  
  198.   As an example, lets create a pop-up menu that uses the window’s current font and displays the icon in the title.  The following code sample illustrates how this is done:
  199.  
  200.  procedure DoItNow;
  201.    var
  202.      ProcID: TPPopUpMenuSpec;  {Define the variable used for the ProcID}
  203.    begin
  204.      ProcID.Num:=0;            {Initialize all the bits to zero values }
  205.      ProcID.UseWindowFont:=true;{Specify that window font is to be used}
  206.      ProcID.IconInTitle:=true; {Specify that selected item’s icon      }
  207.                                {  appears in the pop-up box.           }
  208.                                {Create the pop-up menu using the       }
  209.                                {  integer part of the ProcID…          }
  210.      NewPopUp(1, 110, 20, 209, 20, 'Day of Week:', ProcID.Num, enabled);
  211.  
  212.  
  213.  
  214.   You can use whatever you like best as the ProcID, a single constant, several constants added together, a variable, or the short or 2-byte integer component of a structure or variant record.
  215.  
  216.  
  217.  
  218. Pop-Up Menus on Color Backgrounds
  219. `````````````````````````````````
  220.   Sometimes it may be necessary to place a pop-up menu on a color surface, such as a tool bar.  If you are creating a pop-up menu on a color surface, set the window’s foreground color (by using Color QuickDraw’s RGBForeColor) to the color on which the pop-up menu is being created, then create the menu.  You may change the window’s foreground and background colors at any time without affecting pop-up menus.
  221.  
  222.   Each pop-up menu remembers the color on which it is created, and uses this color when any erasing is performed by the pop-up menu.  An example of this is when the user clicks and holds the pop-up menu.  In such a case, the control’s body temporarily disappears and is replaced by the pop-up menu’s list of items.  The color is used in erasing only if the monitor on which the menu is drawn is set to 4-bits or higher, otherwise the pop-up menu is drawn on a white surface.
  223.  
  224. Also see:  NewPopUpRect and PopUpMenu.
  225.  
  226.   CONST                             {Pop-Up Menu Specifications:       }
  227.     popupNeverDimOutline   = $0100; {Never dim the control's outline   }
  228.     popupNeverDimSelection = $0080; {Never dim the selected item's text}
  229.     popupNeverDimTitle     = $0040; {Never dim the title               }
  230.     popupNoArrow           = $0020; {Hide the "down arrow"             }
  231.     popupMultiSelect       = $0010; {Allow multiple selections         }
  232.     popupUseWFont          = $0008; {Use the window's font for the menu}
  233.     popupIconTitle         = $0004; {Draw icon in the control's title  }
  234.     popupFixedTitle        = $0002; {Display fixed title               }
  235.     popupDefaultType       = $0000; {Default: sys font, 1 item, no icon}
  236.  
  237. ------------------------------------------------------------------------
  238.  
  239. NewPopUpRect
  240. ````````````
  241. Create a new pop-up menu.
  242.  
  243.    pascal void NewPopUpRect (short MenuNumber, Rect *Bounds,
  244.                  Str255 MenuTitle, short procID, Boolean EnabledFlag);
  245.  
  246.    procedure NewPopUpRect (MenuNumber: INTEGER; Bounds: RECT;
  247.                  MenuTitle: string; procID: INTEGER;
  248.                  EnabledFlag: boolean);
  249.  
  250.   NewPopUpRect is identical to the NewPopUp procedure, except that it accepts the Bounds rectangle in place of the individual left, top, right and bottom co-ordinates.
  251.  
  252. ------------------------------------------------------------------------
  253.  
  254. PopUpMenu
  255. `````````
  256. Create a pop-up menu, add more items, or rename existing items.
  257.  
  258.    pascal void PopUpMenu (short MenuNumber, short ItemNumber,
  259.                  Boolean EnabledFlag, Str255 MenuText);
  260.  
  261.    procedure PopUpMenu (MenuNumber, ItemNumber: INTEGER;
  262.                  EnabledFlag: BOOLEAN; MenuText: STRING);
  263.  
  264.   After a pop-up menu is created with NewPopUp or NewPopUpRect, pop-up menu items can then be added to the menu.  Your application should define items in their correct order (i.e., top to bottom) in order to use the full power of this procedure.
  265.  
  266.   MenuNumber specifies the pop-up menu number (from 1 to 255) that is affected in the current window.  If the current window doesn’t belong to your application, or if the specified pop-up menu doesn’t exist, PopUpMenu does nothing.
  267.  
  268.   ItemNumber specifies the pop-up menu’s item number (from 1 to 255) that is affected.
  269.  
  270.   EnabledFlag specifies whether the menu item is enabled or disabled.  The menu item can be selected only when enabled.  When disabled, the pop-up menu item is dimmed and cannot be selected by the user.  The two constants that can be used for this purpose are enabled and disabled.  Pop-up menus and their items can be enabled and disabled by using the EnablePopUp procedure.
  271.  
  272.   MenuText is the pop-up menu item’s name.  If you specify a null string (length equal to zero), Tools Plus will insert a space to prevent anomalous behavior. When a pop-up menu item is first created, certain metacharacters are recognized by Tools Plus to provide special instructions to the Menu Manager.  You may choose to include or exclude these characters within MenuText, however, you should be aware of their effects.  Pop-up menu items can include multiple metacharacters.
  273.  
  274. Note: The Macintosh’s Menu Manager allows only the first 31 items of a
  275.       pop-up menu to be disabled individually.  The entire pop-up menu,
  276.       however, can always be disabled.
  277.  
  278.  
  279.  
  280. Metacharacters
  281. ``````````````
  282.   Metacharacters are symbols that tell the Menu Manager to perform special functions on a menu.  They are recognized and processed only when a menu item is first created, and are ignored (displayed as ordinary characters) when menu items are renamed.  Menu items can include multiple metacharacters or combinations of metacharacters.
  283.  
  284.   Unlike the Macintosh toolbox’s menu routines, Tools Plus removes the semi-colon (;) and Return character ($0D), and does not process them as metacharacters.
  285.  
  286.   ^  Display an icon to the left of the menu item.  The number following
  287.      the caret (^) should be from 1 to 255 (i.e., “^28”).  The Menu
  288.      Manager adds 256 to the number you state to specify a resource ID
  289.      that is in the range of 257 to 511, so if you specify 28, resource
  290.      ID 284 is used (28 + 256 = 284).  These icon resources are
  291.      read from your application.
  292.        Tools Plus tries to use a ‘cicn’ icon if Color QuickDraw is
  293.      available on the Macintosh running your application.  Otherwise, it
  294.      will search for an ‘ICON’ (black and white) icon, then an ‘SICN’
  295.      icon.
  296.        Unlike the equivalent Macintosh toolbox routine, your menu item
  297.      will remain unaffected if the specified icon can’t be found
  298.      (i.e., empty space is not reserved in the menu).
  299.        Be aware that the Menu Manager drawing a ‘cicn’ icon in color
  300.      will do so even if the icon was created using 8-bit colors and the
  301.      monitor is set to 4-bits.  This may produce unsatisfactory results.
  302.      If possible, use 4-bit colors or colors that translate well into
  303.      4-bit colors.
  304.  
  305.   !  Display a special mark to the left of a menu item.  The single
  306.      character that follows the exclamation mark (!) is displayed.  The
  307.      check mark is the default.  (It is best to use the CheckPopUp or
  308.      PopUpMark procedures.)
  309.  
  310.   <  The item is displayed in a special character style.  The single
  311.      character that follows this symbol specifies the style (Bold,
  312.      Italic, Underline, Outline, or Shadow).  Multiple styles can be
  313.      combined, such as “<B<I” for “bold and italic.”  It is best to use
  314.      PopUpStyle to change styles.
  315.  
  316.   To create a “dividing line” between sections of related pop-up menu items, disable the item and use ‘-’ (a minus or dash) as the MenuText value.  You can use the constant mDividingLine for this purpose.
  317.  
  318.   Special care should be taken to create pop-up menu items in their correct order.  If any items are skipped when defining a pop-up menu item (i.e., creating item 3 without first creating 1 and 2) the missing pop-up menu items (1 and 2) are automatically created as blank, disabled items.  Consequentially, metacharacters will not be recognized when the PopUpMenu procedure references these automatically created items; the PopUpMenu procedure will simply rename the existing item.
  319.  
  320.   CONST                    {Menu and Menu Item status }
  321.     enabled       = true;  {enable the menu/item      }
  322.     disabled      = false; {disable the menu/item     }
  323.     mDividingLine = ‘-’;   {Dividing line             }
  324.  
  325. ------------------------------------------------------------------------
  326.